PATHMac OS 8 and 9 Developer Documentation > Interapplication Communication > AppleScript for Scripters >

AppleScript Language Guide

   

Reference

A value of class Reference is a reference to an object. A reference can refer to an application object such as a window or file, or to an AppleScript object such as an item in a list or a property in a record. You can create a value of class Reference by using the A Reference To operator. In addition, applications can return references in response to commands.

A value of class Reference is different from the value of the object to which a reference refers. For example, the reference docNameRef in the following script refers to a name object (name of document 1 of application "AppleWorks") whose value is a string (such as " April Report " ).

tell application "AppleWorks"
    set docNameRef to a reference to the name of the first document
        --result: name of document 1 of application "AppleWorks"
    docNameRef as string --result: "April Report"
end tell

If you change the name of the report to "Revised April Report" and run this script again, the result of the reference will be the same (name of document 1 of application "AppleWorks"), but the value will change ( "Revised April Report " ).

The difference between a value of class Reference and the object it refers to is analogous to the difference between an address and the building it refers to. The address is a series of words and numbers, such as "1414 Maple Street," that identifies the location of the building. It is distinct from the building itself. If the building is replaced with a new building at the same location, the address remains the same.

A value of class Reference created with the A Reference To operator is a structure within AppleScript that refers to (or points to) a specific object.

tell application "AppleWorks"
    set docRef to a reference to the first document
        --result: document 1 of application "AppleWorks"
    name of docRef --result: "New Report"
end tell

In this script, the reference docRef refers to the first document of the application AppleWorks, which happens to be named "New Report". However, the object that docRef points to can change. If you open a second AppleWorks document called "Second Report" and run this script again, it will return the name of the newly opened document, "Second Report".

You can instead create a direct reference to the document "New Report":

tell application "AppleWorks"
    set docRef to a reference to document "New Report"
        --result: document "New Report" of application "AppleWorks"
    name of docRef --result: "New Report"
end tell

If you run this script after opening a second document, it will still return the name of the original document, "New Report". You can also use the alias form to refer to a file whose name or location may change. For more information, see References to Files.

Values of class Reference are similar to pointers in other programming languages, but unlike pointers, references can refer only to objects. Using a reference can sometimes be much more efficient than using an object directly, as shown in the example in the Notes section in List. For related information about using values of class Reference, see The A Reference To Operator.

LITERAL EXPRESSIONS
set itemRef to a reference to item 3 of {1, "hello", 755, 99}
    --result: item 3 of {1, "hello", 755, 99}
set newTotal to itemRef + 45 --result: 800 a reference to the name of the first report
PROPERTIES
Class
The class identifier for the object. This property is read-only, and its value is always reference .
Contents
The value of the object to which the reference refers. The class of the value depends on the reference. For information about how to use the Contents property, see The A Reference To Operator.
ELEMENTS

None

OPERATORS

The A Reference To operator returns a reference as its result. This operator is described in The A Reference To Operator.

COERCIONS SUPPORTED

The application to which an object specified by a reference belongs determines whether the value of the object can be coerced to a desired class.

NOTES

A reference can function as a reference to an object or as an expression whose value is the value of the object specified in the reference. When a reference is the direct parameter of a command, it usually functions as a reference to an object, indicating to which object the command should be sent. In most other cases, references function as expressions, which AppleScript evaluates by getting their values.

The reference front window of application "Apple System Profiler" in the following example functions as a reference to an object. It identifies the object to which the Close command is sent.

close front window of application "Apple System Profiler"

On the other hand, the reference name of the first report in the following example functions as a reference expression:

tell application "Apple System Profiler"
    set reportNameString to name of the first report
end tell

When AppleScript executes this script, it gets the value of the reference name of the first report--a string--and then stores it in the variable reportNameString.

The following script shows an AppleWorks application command, the Make command, which returns a reference:

tell application "AppleWorks"
    -- Create a new document and get a reference to it.
    set docRef to (make new document at beginning ¬
        with properties {name:"New Report"})
    --result: document "New Report" of application "AppleWorks"
end tell
© 1999 Apple Computer, Inc. – (Last Updated 21 May 99)